home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / System / NewIconsV4 / Developers / Autodocs / newicon.doc
Text File  |  1999-03-11  |  9KB  |  266 lines
  1. TABLE OF CONTENTS
  2.  
  3. newicon.library/--Introduction--
  4. newicon.library/FreeNewDiskObject
  5. newicon.library/FreeRemappedImage
  6. newicon.library/GetDefNewDiskObject
  7. newicon.library/GetNewDiskObject
  8. newicon.library/PutNewDiskObject
  9. newicon.library/RemapChunkyImage
  10.  
  11. newicon.library/--Introduction--             newicon.library/--Introduction--
  12.  
  13. The goal behind newicon.library is to offer an interface for the 
  14. application programmer wishing to directly support NewIcons, be it for 
  15. icon editors or Workbench replacements.  This ensures that your product 
  16. will be able to support NewIcons even if the Newicons executable isn't 
  17. running.
  18.  
  19. The standard procedure is to call GetNewDiskObject(), and check if any 
  20. of the ndo_NormalImage or ndo_SelectedImage fields are NULL.  If they are, 
  21. then this icon has no newicon data, so you can use the ndo_StdObject 
  22. pointer to access the regular DiskObject structure.  If you have something 
  23. in ndo_NormalImage and ndo_SelectedImage, then call RemapChunkyImage() 
  24. on them to obtain Image structures remapped to the specified screen.
  25.  
  26. If you know you're dealing with a chunky display, you might wish to handle 
  27. the chunky data yourself, which would be more efficient than remapping to 
  28. an Intuition Image structure and blitting back on your chunky screen.
  29. In that case, don't use RemapChunkyImage(), and handle the 
  30. ndo_#?Image->ChunkyData yourself.
  31.  
  32. Once you're done with your newicon, call FreeRemappedImage() on the 
  33. remapped images to free them up (if you used RemapChunkyImage()).  After 
  34. that, call FreeNewDiskObject() on your NewDiskObject structure (even if 
  35. you only used the DiskObject pointer from it!) to free it.
  36.  
  37. newicon.library/FreeNewDiskObject           newicon.library/FreeNewDiskObject
  38.  
  39.  
  40.    NAME
  41.       FreeNewDiskObject() -- Free all memory allocated in a NewDiskObject.
  42.  
  43.    SYNOPSIS
  44.       FreeNewDiskObject(newdiskobj)
  45.                            A0
  46.  
  47.       VOID  FreeNewDiskObject(struct NewDiskObject *);
  48.  
  49.  
  50.    FUNCTION
  51.       Pretty much like the standard icon.library FreeDiskObject() call.
  52.       It will deallocate any memory allocated for a NewDiskObject, and
  53.       the object itself.  This is the ONLY way to deallocate a NewDiskObject
  54.       structure that has been allocated by GetNewDiskObject().
  55.  
  56.       
  57.    INPUTS
  58.       newdiskobj -- A pointer to a NewDiskObject structure.
  59.  
  60.  
  61.    RESULT
  62.       None.
  63.  
  64.  
  65.    SEE ALSO
  66.       newicon.library/GetNewDiskObject(), icon.library/FreeDiskObject()
  67.  
  68. newicon.library/FreeRemappedImage           newicon.library/FreeRemappedImage
  69.  
  70.  
  71.    NAME
  72.       FreeRemappedImage() -- Frees a remapped image and its pens.
  73.  
  74.  
  75.    SYNOPSIS
  76.       FreeRemappedImage(image, screen)
  77.                           A0     A1
  78.  
  79.       VOID  FreeRemappedImage(struct Image *, struct Screen *)
  80.  
  81.  
  82.    FUNCTION
  83.       This function frees a remapped image and also frees its pens. 
  84.       Therefore you must call it only after you are done with the image:
  85.       if you call it while it is still displayed on the screen, your image
  86.       could see its colors mangled since the pens would be freed.
  87.  
  88.       You must supply a screen argument.  It must either be the same
  89.       passed to RemapChunkyImage, or NULL if the screen has been closed
  90.       in the meantime, so the pens don't need to be released.
  91.  
  92.  
  93.    INPUTS
  94.       image  -- A pointer to a remapped Image structure.
  95.  
  96.       screen -- A pointer to the Screen for which your ChunkyData was
  97.                 remapped, or NULL if the screen has been closed since then.
  98.  
  99.  
  100.    RESULT
  101.       None.
  102.  
  103.  
  104.    SEE ALSO
  105.       newicon.library/RemapChunkyImage()
  106.  
  107. newicon.library/GetDefNewDiskObject      newicon.library/GetDefNewDiskObject
  108.  
  109.    NAME
  110.         GetDefNewDiskObject - read default disk object, with NewIcons
  111.                               support. (V40)
  112.  
  113.    SYNOPSIS
  114.         newdiskobj = GetDefNewDiskObject(def_type)
  115.           D0                               D0
  116.  
  117.         struct NewDiskObject *GetDefNewDiskObject(LONG);
  118.  
  119.    FUNCTION
  120.         Pretty much like the standard icon.library GetDiskObject() call.
  121.         In fact, it merely calls it, embedding the returned disk object
  122.         in a NewDiskObject structure, with the NewIcons imagery if the
  123.         default disk object had any.
  124.  
  125.         The valid def_types can be found in workbench/workbench.h and
  126.         currently include WBDISK thru WBGARBAGE.  If the call fails,
  127.         it will return zero.  The reason for the failure may be obtained
  128.         via IoErr().
  129.  
  130.  
  131.    INPUTS
  132.         def_type - default icon type (WBDISK thru WBKICK).  Note that the
  133.                    define 'WBDEVICE' is not currently supported.
  134.  
  135.  
  136.    RESULTS
  137.         newdiskobj -- the default Workbench disk object in question
  138.  
  139.    SEE ALSO
  140.         icon.library/GetDefDiskObject()
  141.  
  142. newicon.library/GetNewDiskObject             newicon.library/GetNewDiskObject
  143.  
  144.  
  145.    NAME
  146.       GetNewDiskObject() -- Read a disk object, with NewIcons support.
  147.  
  148.    SYNOPSIS
  149.       newdiskobj = GetNewDiskObject(name)
  150.         D0                           A0
  151.  
  152.       struct NewDiskObject *GetNewDiskObject(char *);
  153.  
  154.    FUNCTION
  155.       Pretty much like the standard icon.library GetDiskObject() call.
  156.       It will read the Workbench disk object specified in the name parameter,
  157.       adding the ".info" suffix itself, and return a filled NewDiskObject
  158.       structure.  If the call fails, it returns zero.  The reason for the
  159.       failure can be obtained by calling IoError().
  160.       
  161.       This routine can be used if you wish to obtain a standard diskobject,
  162.       with separate pointers to NewIcons chunky data if there's NewIcons
  163.       imageries present in the loaded disk object.  No further processing
  164.       is done (i.e. the chunky data aren't remapped, etc...)
  165.        
  166.       Once finished with it, you must use FreeNewDiskObject() to free the
  167.       memory that was allocated for it.
  168.  
  169.  
  170.    INPUTS
  171.       name -- The name (char *) of the object (without the ".info" suffix).
  172.  
  173.  
  174.    RESULT
  175.       newdiskobj -- a filled NewDiskObject structure.  You must call
  176.                     FreeNewDiskObject() once you're done with it.
  177.  
  178.  
  179.    SEE ALSO
  180.       newicon.library/FreeNewDiskObject(), newicon.library/RemapChunkyData(),
  181.       icon.library/GetDiskObject()
  182.  
  183. newicon.library/PutNewDiskObject             newicon.library/PutNewDiskObject
  184.  
  185.  
  186.    NAME
  187.       PutNewDiskObject() -- write a NewDiskObject to disk.
  188.  
  189.    SYNOPSIS
  190.       status = PutNewDiskObject(name, newdiskobj)
  191.         D0                       A0     A1
  192.  
  193.       BOOL  PutNewDiskObject(char *, struct NewDiskObject *);
  194.  
  195.  
  196.    FUNCTION
  197.       Pretty much like the standard icon.library PutDiskObject() call.
  198.       This routine will write a NewDiskObject structure and its related
  199.       information to disk as a standard icon, encoding the chunky data
  200.       (if present in the structure) as NewIcons tooltypes in the process.
  201.  
  202.       The filename of the info file is specified as the name parameter,
  203.       which will automaticaly get the ".info" suffix added.  If the call
  204.       fails, it returns zero.  The reason for the failure can be obtained
  205.       by calling IoError().
  206.       
  207.  
  208.    INPUTS
  209.       name -- The name (* char) of the object (without the ".info" suffix).
  210.       newdiskobj -- A pointer to a NewDiskObject structure.
  211.  
  212.  
  213.    RESULT
  214.       status -- TRUE if the call was successfull, else FALSE.
  215.  
  216.  
  217.    SEE ALSO
  218.       newicon.library/FreeNewDiskObject(), 
  219.       newicon.library/GetNewDiskObject(), icon.library/PutDiskObject()
  220.  
  221. newicon.library/RemapChunkyImage             newicon.library/RemapChunkyImage
  222.  
  223.  
  224.    NAME
  225.       RemapChunkyImage() -- Remaps a chunky image to be displayed on screen
  226.  
  227.    SYNOPSIS
  228.       image = RemapChunkyImage(chunkyimage, screen)
  229.         D0                       A0           A1
  230.  
  231.       struct Image *RemapChunkyImage(struct ChunkyImage *, struct Screen *);
  232.  
  233.    FUNCTION
  234.       Remaps a ChunkyImage to be displayed on a screen.  Caller must either
  235.       be the owner of the screen, or have locked it.  Under KS 3.0 (V39) and
  236.       up, it will use ObtainBestPen() if screen has shareable pens.
  237.       Otherwise will use the available colors.
  238.  
  239.       The image is returned as an Intuition Image structure, remapped so
  240.       chunky data palette match as closely as possible with the target
  241.       screen's palette, depending on the precision setting chosen by the
  242.       user in the NewIconsPrefs editor, and the available pens.
  243.  
  244.       Once done with your image, you should call FreeRemappedImage() to free
  245.       it and any allocated pens.
  246.  
  247.  
  248.    INPUTS
  249.       chunkydata -- A pointer to a ChunkyImage structure.
  250.       screen     -- A pointer to the destination Screen.
  251.  
  252.  
  253.    RESULT
  254.       Image -- An Intuition Image structure, or NULL if it fails.
  255.  
  256.  
  257.    NOTES
  258.       If the user has enabled the RTG Mode in the NewIconsPrefs, then the
  259.       remapped image will be in Fast RAM (if there's any, else it will
  260.       try to allocate Chip RAM instead).
  261.  
  262.  
  263.    SEE ALSO
  264.       newicon.library/FreeRemappedImage()
  265.  
  266.